home *** CD-ROM | disk | FTP | other *** search
/ Programming Sound Cards / Programming Sound Cards.iso / sound_30 / mpu401.doc < prev    next >
Text File  |  1995-01-01  |  22KB  |  727 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.             The following is a synopsis of the functions contained in
  8.             the MPU401 Library.
  9.  
  10.  
  11.             Data Structures
  12.  
  13.  
  14.               The event structure:
  15.  
  16.               The fundamental data structure in the MPU401 library is
  17.               that of an MPU event. An event consists of a timing  delay
  18.               byte, a status (opcode) byte and 0 or more data bytes. One
  19.               or more of the previously defined bytes may be omitted in
  20.               the MIDI or MPU401 data streams. For example, the opcode
  21.               byte is omitted if the event is of the same type as the
  22.               previous event. Some event types omit the initial timing
  23.               byte. The MPU401 library parses this input and deposits
  24.               the information in a consistent format for ease of
  25.               processing. The programmer needn't be concerned with most
  26.               of the exceptions to the basic data format, the library
  27.               will handle them at the driver level.
  28.  
  29.               the C structure describing an MPU401 event is as follows:
  30.  
  31.               
  32.  
  33.             struct event
  34.                  {
  35.                    /* lenth of data portion (if any) */
  36.                  unsigned char dlen;
  37.                    /* opcode or 0 if running status */
  38.                  unsigned char status;
  39.                    /* timing delay value or
  40.                       255 if opcode is a MPU message */
  41.                  unsigned char tbyte;
  42.                    /* SYSTEM EXCLUSIVEs are the only events that will
  43.                     exceed 4 bytes of data, so most events will fit into
  44.                     the "data" member, if SYSTEM EXCLUSIVE data
  45.                     exceeds 4 bytes the dptr member points to a
  46.                      calloc()ed data  buffer */
  47.                  union {
  48.                       unsigned char *dptr; /* data buffer ptr */
  49.                       unsigned char data[4];/* or data buffer */
  50.                       } d;
  51.                  struct event *n; /* next event in list */
  52.                  };
  53.  
  54.             To parse an event:
  55.  
  56.                  if e.tbyte < 240
  57.                       {
  58.                       if e.status > 239
  59.                            event is a MPU MARK (CLOCK, END OF MEASURE
  60.             etc)
  61.  
  62.                     MPU401.DOC: Copyright 1988, G.E.S Consulting
  63.                                        Page 1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.                       else if e.status == 0
  74.                            event is same as last MIDI event
  75.                       else [e.status > 0 < 240]
  76.                            event is a MIDI event
  77.                       }
  78.                  else (e.tbyte == 255)
  79.                       event is an MPU Message (Data Request, SYSEX,
  80.             etc).
  81.  
  82.             
  83.  
  84.  
  85.             Commands
  86.  
  87.             The following commands return 0 upon success, -1 on MPU
  88.             error, unless otherwise noted. For more detailed reference,
  89.             see the technical manual that came with your MPU401.
  90.  
  91.  
  92.               int reset_mpu()
  93.  
  94.               Resets the MPU401 to its power up state. NOTE: this
  95.               function will always return -1 after the MPU has been put
  96.               into UART mode.
  97.  
  98.  
  99.               int get_version()
  100.  
  101.               Gets the internal version and revision data from the
  102.               MPU401. The version and revision are represented in BCD in
  103.               the high and low bytes of the return value. The revision
  104.               level is mapped to the alphbet with 1 == A , 2==B and so
  105.               on. This command is not supported on MPU401s previous to
  106.               release 1.2B. Example return:
  107.                  if MPU401 is level 1.5A, get_version returns 0x1501.
  108.  
  109.  
  110.               int uart_mode_on()
  111.  
  112.               Puts the MPU401 into dumb uart mode. Use reset_mpu() to
  113.               return to intellegent mode. The remainder of this manual
  114.               refers to intellegent mode operations only.
  115.  
  116.  
  117.             initialization switches
  118.  
  119.             The following functions alter the default operation of the
  120.             MPU401. Once called the only way the default conditions can
  121.             be restored is to reset the MPU via reset_mpu(). When used,
  122.             these functions are normally called once, at the beginning
  123.             of the application.
  124.  
  125.  
  126.  
  127.  
  128.                     MPU401.DOC: Copyright 1988, G.E.S Consulting
  129.                                        Page 2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.               int all_notes_off()
  140.  
  141.               Disables the MPU from sending out any ALL NOTES OFF
  142.               message received from midi in. Also prevents ALL NOTES OFF
  143.               messages from being send due to the interaction of MIDI In
  144.               and the channel reference tables when all notes have been
  145.               turned off.
  146.  
  147.  
  148.               int no_real_time()
  149.  
  150.               Prevents the MPU401 from creating REAL TIME messages for
  151.               the MIDI Out Port (Clock, Start, Stop, Continue). Normaly
  152.               Midi Clocks are constantly send.
  153.  
  154.  
  155.               int all_thru_off()
  156.  
  157.               Modifies the way the midi_thru() (see below) command
  158.               works. Normaly midi_thru(OFF) only affects unfiltered
  159.               channels. If all_thru_off() has been called midi_thru(OFF)
  160.               affects ALL channels.
  161.  
  162.  
  163.               int with_timing_byte_on()
  164.  
  165.               Modifies the way the MPU passes data the the host when the
  166.               MPU is in STOP (not playing or recording) mode. By
  167.               default, the MPU sends only opcode and data bytes when in
  168.               STOP mode. If with_timing_byte_on() is called, all events
  169.               are sent with a leading timing byte, regardless of MPU
  170.               mode. The MPU401 Driver makes this call during
  171.               initialization.
  172.  
  173.  
  174.               int mode_messages_on()
  175.  
  176.               This function allows MIDI mode messages (OMNI ON, POLY,
  177.               etc) to be passed to the host. By default these messages
  178.               are masked.
  179.  
  180.  
  181.               int exclusive_thru_on()
  182.  
  183.               Allows SYSTEM EXCLUSIVE messages received at MIDI In to be
  184.               passed through to Midi Out. Normaly these messages are
  185.               masked.
  186.  
  187.  
  188.               int common_to_host_on()
  189.  
  190.               Allows SYSTEM COMMON messages to be forwarded to the host.
  191.               Normaly these messages are masked.
  192.  
  193.  
  194.                     MPU401.DOC: Copyright 1988, G.E.S Consulting
  195.                                        Page 3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.               int real_time_to_host_on()
  206.  
  207.               Allows Midi REAL TIME messages received at Midi In to be
  208.               passed to the host. Normaly these messages are masked.
  209.  
  210.  
  211.             Channel Reference Table Control
  212.  
  213.             For the following commands the mode argument is either ON or
  214.             OFF (see midi.h).
  215.  
  216.  
  217.               int table_a(mode)
  218.  
  219.               Turns Channel Reference Table A On or OFF.
  220.  
  221.  
  222.               int table_b(mode)
  223.  
  224.               Turns Channel Reference Table B On or OFF.
  225.  
  226.  
  227.               int table_c(mode)
  228.  
  229.               Turns Channel Reference Table C On or OFF.
  230.  
  231.  
  232.               int table_d(mode)
  233.  
  234.               Turns Channel Reference Table D On or OFF.
  235.  
  236.  
  237.               int set_channel_reference(unsigned table,unsigned channel)
  238.  
  239.               Associates a particular channel to a particular Channel
  240.               Reference Table. The "table" argument is 0 - 3 for tables
  241.               'A' - 'D', the "channel" argument is 0 - 15 for channels 1
  242.               - 16, respectively.
  243.  
  244.  
  245.             Clock Control
  246.  
  247.  
  248.               int clock(mode)
  249.  
  250.               Selects the clock the MPU401 will use for recording and
  251.               playback where mode is one of INTERNAL_CLOCK, FSK_CLOCK or
  252.               MIDI_CLOCK (see midi.h).
  253.  
  254.  
  255.               int set_fsk_resolution(mode)
  256.  
  257.               Selects the timebase for the TAPE SYNC clock where "mode"
  258.               is either FSK_TO_INTERNAL or FSK_TO_MIDI (see midi.h).
  259.  
  260.                     MPU401.DOC: Copyright 1988, G.E.S Consulting
  261.                                        Page 4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.               int set_timebase(type)
  272.  
  273.               Sets the resolution of the internal clock to one of six
  274.               predefined values. The default is TB_120 or 120 ticks per
  275.               beat (quarter note) (see midi.h).
  276.  
  277.  
  278.             Metronome Control
  279.  
  280.  
  281.               int set_clocks_per_beep(unsigned clocks)
  282.  
  283.               Sets the number of MIDI ticks per metronome beep. The
  284.               default is 12 or one beep per eighth note.
  285.  
  286.  
  287.               int set_beeps_per_measure(unsigned beeps)
  288.  
  289.               Sets the number of beeps (above) per measure. The default
  290.               is 8.
  291.  
  292.  
  293.               int metronome_on(unsigned accent)
  294.  
  295.               Turns on the MPU401 metronome. If "accent" is nonzero, the
  296.               metronome will sound primary and secondary accents. If the
  297.               "accent" argument is zero, the metronome will sound only
  298.               primary accents.
  299.  
  300.  
  301.               int metronome_off()
  302.  
  303.               Turns off the metronome.
  304.  
  305.  
  306.             Tempo Control
  307.  
  308.  
  309.               int get_tempo()
  310.  
  311.               Returns the current tempo setting of the MPU401. The value
  312.               is in quarter notes per minute.
  313.  
  314.  
  315.               int set_tempo(unsigned beats_per_minute)
  316.  
  317.               Sets the MPU401s tempo to "beats_per_minute" quarter note
  318.               beats per minute.
  319.  
  320.  
  321.               int set_relative_tempo(unsigned newtemp)
  322.  
  323.               Temporarily modifies the MPUs tempo by the ration
  324.               "newtemp"/64.
  325.  
  326.                     MPU401.DOC: Copyright 1988, G.E.S Consulting
  327.                                        Page 5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.               Eg. If tempo = 60, the call set_relative_tempo(96) would
  338.               result in a temporary effective tempo of 90. This command
  339.               is normaly used with the "Conductor" feature of the
  340.               MPU401.
  341.  
  342.  
  343.               int reset_relative_tempo()
  344.  
  345.               Restores the MPUs tempo to that of the last set_tempo()
  346.               command. Cancels any relative tempo changes.
  347.  
  348.  
  349.               int set_graduation(unsigned value)
  350.  
  351.               Sets the rate of RELATIVE TEMPO (above) change. 0 =
  352.               immediate, 1 = slowest, 255 = fastest.
  353.  
  354.  
  355.             Data Flow Control
  356.  
  357.  
  358.               int active_tracks(unsigned trackmap)
  359.  
  360.               Tells the MPU401 which tracks are to be played on the next
  361.               PLAY request. Argument trackmap is a bit map of the
  362.               channels to activate. The bitmap can be constructed by
  363.               ORing the track defines in midi.h. Eg.
  364.               active_tracks(TRACK_1|TRACK_8) to play tracks 1 and 8.
  365.               This command does not put the MPU in PLAY mode it only
  366.               informs it of what you intend to play.
  367.  
  368.  
  369.               int acceptable_channels(unsigned chanmap)
  370.  
  371.               Tells the MPU which channels to recognize at Midi In. By
  372.               default ALL 16 channels are accepted. Argument chanmap is
  373.               a bitmap of the 16 possible channels. The bitmap can be
  374.               constructed by ORing the defines in midi.h. Eg.
  375.               acceptable_channels(CHANNEL_1|CHANNEL_2) causes the MPU to
  376.               recognize only channels 1 and 2. All other channels are
  377.               passed through to Midi Out unprocessed (unless
  378.               all_thru_off() and midi_thru(OFF) have been called).
  379.  
  380.  
  381.             Switches
  382.  
  383.             The "mode" argument is either ON or OFF for the following
  384.             commands.
  385.  
  386.  
  387.               int bender(mode)
  388.  
  389.               Enable/disable continuous controller data sent to host.
  390.               Default is OFF, data is not sent.
  391.  
  392.                     MPU401.DOC: Copyright 1988, G.E.S Consulting
  393.                                        Page 6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.               int midi_thru(mode)
  404.  
  405.               Enable/disable Midi In being passed through to Midi Out.
  406.               Default is ON, Midi In -> Midi Out (Makes my pf85 sound
  407.               real wierd!)
  408.  
  409.  
  410.               int data_in_stop_mode(mode)
  411.  
  412.               Enable/Disable events occurring when MPU is in STOP mode
  413.               being sent to the host. Default is OFF, data is sent only
  414.               during RECORD mode.
  415.  
  416.  
  417.               int send_measure_end(mode)
  418.  
  419.               Enable/Disable MEASURE END MPU Messages. Default is ON,
  420.               measure end messages are sent to the host.
  421.  
  422.               NOTE: the current implementation of the MPU401 library
  423.               looks for an END OF MEAURE event before completing it's
  424.               record routine. Therefore this function should be called
  425.               only with the ON argument or mpu.c should be modified.
  426.  
  427.  
  428.               int conductor(mode)
  429.  
  430.               Enable/disable the CONDUCTOR feature of the mpu. Default
  431.               is OFF, conductor data is not requested.
  432.  
  433.  
  434.               int real_time_affection(mode)
  435.  
  436.               Enable/disable MPU401 response to REAL TIME Messages
  437.               (Start, Stop, Continue) at the MIDI In port. Default is ON
  438.               the MPU will respond to REAL TIME Messages at MIDI In.
  439.  
  440.  
  441.               int clock_to_host(mode)
  442.  
  443.               Enable/disable clock messsages to host. Default is OFF,
  444.               clock events are not sent.
  445.  
  446.  
  447.               int exclusive_to_host(mode)
  448.  
  449.               Enable/disable SYSTEM EXCLUSIVE Messages. Default = OFF,
  450.               system exclusive messages are filtered by the MPU410
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.                     MPU401.DOC: Copyright 1988, G.E.S Consulting
  459.                                        Page 7
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.               Counter Control
  470.  
  471.  
  472.               int clear_play_counters()
  473.  
  474.               Clears the play counters for all active tracks. Normaly
  475.               called before a "play from beginning of track" operation.
  476.  
  477.  
  478.               int clear_play_map()
  479.  
  480.               Clears the MPU401 play map!
  481.  
  482.  
  483.               int clear_record_counter()
  484.  
  485.               Clears the record counter, but never needs to be called as
  486.               the MPU does this prior to going into RECORD mode anyway.
  487.               Provided for completeness.
  488.  
  489.  
  490.               int get_play_counter(unsigned track)
  491.  
  492.               Returns the value of the play counter for the requested
  493.               track. Argument "track" is a value between 0 and 7
  494.               corresponding to tracks 1- 8.
  495.  
  496.  
  497.               int send_play_counters(unsigned trackmap)
  498.  
  499.               Tells the MPU which play counters to send during the next
  500.               "punch in" operation. Argument "trackmap" is constructed
  501.               as under "active_tracks()" above.
  502.  
  503.  
  504.               int get_record_counter()
  505.  
  506.               Returns the current value of the record counter.
  507.  
  508.  
  509.             IO primitives
  510.  
  511.  
  512.               int mpu_init()
  513.  
  514.               Installs the MPU401 driver. Should be one of the first
  515.               things you do in your program.
  516.  
  517.  
  518.               int mpu_close()
  519.  
  520.               UnInstalls the MPU401 driver. Should be the last thing
  521.               your program does before it exits. If you dont do this
  522.               your system will crash.
  523.  
  524.                     MPU401.DOC: Copyright 1988, G.E.S Consulting
  525.                                        Page 8
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.               int want_to_send_data(unsigned track,
  536.                                      char *data,unsigned len)
  537.  
  538.               Send a MIDI message asyncronously to the MPU401. Argument
  539.               "track" is a value 0 - 7 corresponding to tracks 1 - 8.
  540.               Buffer "data" contains a valid MIDI message (without
  541.               leading timing byte). "len" is the count of data bytes in
  542.               Buffer "data". Should NOT be used on "active" tracks
  543.               during playback. The MIDI message may not be of the SYSTEM
  544.               type (use want_to_send_system() below). See demo file
  545.               notes.c for and example of how this function can be used.
  546.  
  547.  
  548.               int want_to_send_system(char *data,unsigned len)
  549.  
  550.               Similar to "want_to_send_data()" above except that the
  551.               MIDI message argument will contain a SYSTEM class message.
  552.  
  553.  
  554.               struct event *get_event(unsigned char *running,unsigned
  555.                    timeout)
  556.  
  557.               Accumulates the next message from the mpu401. Argument
  558.               "running" is a pointer to a byte sized data space where
  559.               RUNNING STATUS information will be kept. The space should
  560.               be initialized to 0 before each "record" or "play"
  561.               operation. Argument "timeout" is the maximum
  562.               intercharacter time to wait, in seconds. Returns a pointer
  563.               to a filled event structure or a null pointer if out of
  564.               memory or timed out. See data.c demo for an example.
  565.  
  566.             
  567.  
  568.             Event Allocation
  569.  
  570.  
  571.               int event_list_init(unsigned maxevents)
  572.  
  573.               Should be one of the first thing your program does.
  574.               Creates a pool of event structures for you and the
  575.               interrupt handler to share. Maxevents is the highest
  576.               number of events you want in thousands. This is so you can
  577.               reserve some memory for other things (like forking a
  578.               shell, see play.c). To use all available memory, just pass
  579.               a large request like 999 or 9999. Returns the number of
  580.               events in the free pool.
  581.  
  582.  
  583.               struct event *event_alloc()
  584.  
  585.               Grab an event structure from the free pool.
  586.  
  587.  
  588.  
  589.  
  590.                     MPU401.DOC: Copyright 1988, G.E.S Consulting
  591.                                        Page 9
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.               void event_free(struct event *p)
  602.  
  603.               Return an event structure to the free pool.
  604.  
  605.  
  606.               long events_available()
  607.  
  608.               Returns the number of unallocated events remaining.
  609.  
  610.             
  611.  
  612.             Queue Manipulation
  613.  
  614.             The MPU Driver provided in the MPU401 library has two modes:
  615.             NORMAL and INTERRUPT mode. In NORMAL mode the driver behaves
  616.             much the same as any serial communications driver. You send
  617.             commands and retrieve events via get_event() calls. In
  618.             INTERRUPT mode, you set up input, and output queues, issue a
  619.             record or play start command and the driver does the rest.
  620.             It will satisfy MPU401 requests for track data, and store
  621.             incomming MIDI data in the queues that have been set up.
  622.             Your program can go off and do something useful (see play.c)
  623.             while the driver handles all the nitty gritty stuff.
  624.  
  625.             The following functions apply to INTERRUPT MODE only.
  626.  
  627.  
  628.               int que_done()
  629.  
  630.               Returns true when the current PLAY or RECORD operation has
  631.               completed.
  632.  
  633.  
  634.               int set_play_que(int queno,struct event *qp)
  635.  
  636.               Instructs the driver to satisfy MPU TRACK DATA requests
  637.               for track "queno" from the list of events pointed to by
  638.               "qp". "queno" is 0 - 7 corresponding to tracks 1 - 8.
  639.  
  640.  
  641.               int set_record_que(struct event **qp)
  642.  
  643.               Instructs the driver to construct a list of events
  644.               anchored to *qp where qp is the address of a pointer to an
  645.               event structure. The driver will allocate event structures
  646.               as needed and chain them to *qp. (See record.c and play.c)
  647.  
  648.  
  649.               int reset_ques()
  650.  
  651.               Decouples and resets the drivers queue pointers. DOES NOT
  652.               effect any data that may be contained in the queues. The
  653.               driver simply forgets about them.
  654.  
  655.  
  656.                     MPU401.DOC: Copyright 1988, G.E.S Consulting
  657.                                        Page 10
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.               int record_start(), play_start()
  668.  
  669.               Places driver in INTERRUPT MODE and begins the function
  670.               named. If play ques have been set up and active_tarcks()
  671.               called for the corresponding tracks, track data will be
  672.               played during a RECORD operation.
  673.  
  674.  
  675.               record_stop(), play_stop()
  676.  
  677.               Interrupts PLAY or RECORD, returns driver to NORMAL mode.
  678.               NOTE: record_stop() will take effect at the end of the
  679.               measure being recorded when the function is called.
  680.  
  681.  
  682.             
  683.                  NORMAL MODE Commands
  684.  
  685.  
  686.               mpu_control(unsigned char command)
  687.  
  688.               Provides a NORMAL MODE interface to the PLAY and RECORD
  689.               functions. The command argument consists of the ORing of
  690.               values from the following groups (max 1 from each group):
  691.  
  692.                 START_RECORD, STOP_RECORD                Group 1
  693.                 START_PLAY, STOP_PLAY                    Group 2
  694.                 MIDI_START, MIDI_STOP, MIDI_CONTINUE     Group 3
  695.  
  696.                 When using this mode all MPU requests must be satisfied
  697.                 under your program,s control. get_event should be called
  698.                 in a loop and the opcode byte examined to determine
  699.                 appropriate action. send_message may be used to output
  700.                 events to the MPU401.
  701.  
  702.  
  703.               int send_message(struct event *p)
  704.  
  705.               Forward the event pointed to by "p" to the MPU401.
  706.               p->tbyte is a delay value between 0 and 239 or 255
  707.               p->status is 0 (running status [you maintain it]
  708.                            or 0x80 - 0xef or 0xf8 or 0xf9 or 0xfc (when
  709.                                 tbyte < 240)
  710.                            or 0xf8 or 0xff if tbyte == 255
  711.               p->dlen is length of data
  712.               p->d.data is data appropriate to p->status
  713.  
  714.               
  715.  
  716.             int error(char *s)
  717.  
  718.               A dummy error reporting routine. ie. printf("%s\n",s);
  719.  
  720.  
  721.  
  722.                     MPU401.DOC: Copyright 1988, G.E.S Consulting
  723.                                        Page 11
  724.  
  725.  
  726.  
  727.